Skip to content

persist: audit and cut per-shard metric cardinality - #38664

Merged
SangJunBak merged 4 commits into
mainfrom
persist-metric-audit
Sep 11, 2026
Merged

persist: audit and cut per-shard metric cardinality#38664
SangJunBak merged 4 commits into
mainfrom
persist-metric-audit

Conversation

@SangJunBak

@SangJunBak SangJunBak commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Problem:

Every per-shard metric family exports one series per shard in every process holding a handle to it, which is the bulk of persist's /metrics payload. Much of it is dead (on no curated dashboard) or only ever read summed, so the per-shard breakdown is cardinality no query uses.

Solution:

Audit the surface and cut by disposition:

  • Dropped (unused): live_writers, rewrite_part_count, inline_backpressure_count (never incremented), since/upper (frontiers are in mz_internal.mz_frontiers), schema_registry_version_count, inline_part_bytes, batch_part_version_bytes.
  • Renamed to process level: the 3 pubsub shard_pubsub_diff_* counters → pubsub_client_receiver_diff_*.
  • Kept name, dropped shard/name labels: the 3 backpressure_* families (only ever read summed); shared handles now sum live operator contributions via GaugeContribution.
  • Folded to a count: per-shard stale_version 0/1 gauge → process-level mz_persist_stale_shard_count, collected alongside mz_persist_shard_count in one walk of the shards map.

https://claude.ai/code/artifact/cadbde1e-53ea-4e1d-a7a1-197c799e65c9

SangJunBak and others added 4 commits September 3, 2026 18:09
`mz_persist_shard_live_writers` and `mz_persist_shard_rewrite_part_count`
appear on no dashboard. `mz_persist_shard_inline_backpressure_count` was
registered together with inline writes but never incremented, so the
panel that plots it has always shown zero.

Every per-shard family costs one series per shard in every process that
holds a handle to that shard, which is where the persist share of the
environmentd /metrics payload comes from.
Six per-shard families were only ever read summed over all shards, so
the shard label bought nothing but one series per shard per process.

The three `mz_persist_backpressure_*` families keep their names and lose
their labels. They are set by the persist_source backpressure operator,
which never runs in environmentd, so there every one of those series was
a zero. The gauge among them now reads as the sum over live operator
instances, each contributing its most recent value through
`GaugeContribution` and withdrawing it on drop.

The operator's metric bundle, `BackpressureOperatorMetrics`, is shared
with the upsert operator. It now holds plain handles, and each owner
keeps its own series alive: the persist client through its process-level
`BackpressureMetrics`, upsert through the new per-worker
`UpsertBackpressureMetrics`.

The three `mz_persist_shard_pubsub_diff_*` counters move next to the
other pubsub receiver metrics as
`mz_persist_pubsub_client_receiver_diff_{applied,not_applied_stale,not_applied_out_of_order}`.
`mz_persist_shard_since`, `mz_persist_shard_upper`,
`mz_persist_shard_stale_version`,
`mz_persist_shard_schema_registry_version_count`,
`mz_persist_shard_inline_part_bytes` and
`mz_persist_shard_batch_part_version_bytes` appear on no curated
dashboard, only on the everything dump. Frontiers per collection are in
`mz_internal.mz_frontiers`, `mz_persist_shard_count` already counts
shards, and each of the two `_bytes` families has a `_count` sibling on
the shard dashboard.

The release sign-off reference counted `mz_persist_shard_upper` series
to get a shard count and now points at `mz_persist_shard_count`.
The audit dropped the per-shard `mz_persist_shard_stale_version` 0/1
gauge along with the other per-shard families. Its signal has real
coarse value though: it is the rollout / mixed-version progress signal,
telling us how many shards a process still holds at a state version
behind its own build.

Fold it to a process-level `mz_persist_stale_shard_count`: the sum of the
old per-shard flag, O(1) series per process instead of one per shard.
`ShardMetrics` carries a plain `stale: AtomicBool` (not a registered
series) that the CaS apply path sets.

Both process-level shard aggregates (this and the existing
`mz_persist_shard_count`) are sums over the shards map, so a
`register_computed_gauge` closure apiece would lock and walk the map once
per gauge per scrape. Collect them in one pass instead: a
`ShardsAggregateMetrics` collector shares the `shards` map and folds both
totals in a single walk.

Also document `LockingTypedState.shard_metrics`, now retained only to
keep the shard's series registered while the state is cached.
@mtabebe mtabebe changed the title Persist metric audit persist: audit and cut per-shard metric cardinality Sep 10, 2026
@mtabebe
mtabebe self-requested a review September 10, 2026 18:07
@mtabebe
mtabebe marked this pull request as ready for review September 10, 2026 18:29
@mtabebe
mtabebe requested review from a team as code owners September 10, 2026 18:29
@SangJunBak

Copy link
Copy Markdown
Contributor Author

Did another pass and everything looks good! I'll make a followup ticket to do the dashboard changes one this goes out (should be 26.43.0)

@SangJunBak
SangJunBak merged commit 11e6a79 into main Sep 11, 2026
89 checks passed
@SangJunBak
SangJunBak deleted the persist-metric-audit branch September 11, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants